home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 6 / CU Amiga Magazine's Super CD-ROM 06 (1996)(EMAP Images)(GB)(Track 1 of 4)[!][issue 1997-01].iso / cucd / magazine / executive_v2.00 / data / developers.lzx / ExecutiveAPI / ExecutiveAPI.doc < prev    next >
Text File  |  2001-12-06  |  9KB  |  267 lines
  1. TABLE OF CONTENTS
  2.  
  3. ExecutiveAPI/--background--
  4. ExecutiveAPI/--usage--
  5. ExecutiveAPI/EXAPI_CMD_ADD_CLIENT
  6. ExecutiveAPI/EXAPI_CMD_REM_CLIENT
  7. ExecutiveAPI/EXAPI_CMD_GET_NICE
  8. ExecutiveAPI/EXAPI_CMD_SET_NICE
  9. ExecutiveAPI/--background--                      ExecutiveAPI/--background--
  10.  
  11.    PURPOSE
  12.     ExecutiveAPI is a simple, easy to use application programmers
  13.     interface to some Executive features. As you know, there are
  14.     programs that require an entry in Executive.prefs file to, for
  15.     example, keep task's priority above all scheduled tasks. They
  16.     assume that task priorities will remain unchanged, which is
  17.     ok although it's not guaranteed anywhere. With ExecutiveAPI,
  18.     it's possible to configure Executive directly from the application.
  19.  
  20.    FEATURES
  21.     * Add/remove client
  22.  
  23.       The purpose of this is to prevent Executive from exiting/
  24.           restarting while your program is running.
  25.  
  26.     * Get/set nice-value
  27.  
  28.       Easily get or set the nice-value of a task.
  29.  
  30.     * Get priority
  31.  
  32.       Because there is no GetTaskPri() function in exec.library, you
  33.       can't read task's real priority from task-structure while
  34.       Executive is running, because it may be the scheduling priority.
  35.  
  36.     * Add entries to Executive's "watched" tasks list
  37.  
  38.       Lets you control task scheduling directly without having
  39.       to add entries to Executive.prefs file.
  40.  
  41.    AUTHOR
  42.     Petri Nordlund <petrin@megabaud.fi>
  43.  
  44.    HISTORY
  45.     V1.00  First release
  46.  
  47. ExecutiveAPI/--usage--                           ExecutiveAPI/--usage--
  48.  
  49.     Communication with Executive is done trough a public message
  50.     port, "Executive_server". Simple command messages can be sent
  51.     to this port. The necessary steps to send a command are:
  52.  
  53.        1. Initialize ExecutiveMessage structure
  54.        2. Send the message to the port
  55.        3. Wait for reply
  56.        4. Delete the message
  57.  
  58.     The message, commands and possible errors are defined in
  59.     ExecutiveAPI.h file.
  60.  
  61.     It's important that the "ident" item in ExecutiveMessage
  62.     structure is always initialized to 0, as this is used by
  63.     Executive to separate ExecutiveAPI messages and messages
  64.     from Executive client programs.
  65.  
  66.     The "command" must always be given, "task", "taskname" and
  67.     "value1-4" items only if the command requires them.
  68.     "taskname" only works with EXAPI_CMD_WATCH command.
  69.  
  70.     The "error" item will be zero if everything went well, otherwise
  71.     an error occurred.
  72.  
  73.     The included example program demonstrates all ExecutiveAPI
  74.     commands.
  75.  
  76.     Please don't hesitate to ask me about ExecutiveAPI usage.
  77.     My email address is <petrin@megabaud.fi>.
  78.  
  79. ExecutiveAPI/EXAPI_CMD_ADD_CLIENT                ExecutiveAPI/EXAPI_CMD_ADD_CLIENT
  80.  
  81.    NAME
  82.     EXAPI_CMD_ADD_CLIENT - Add a program as Executive client
  83.  
  84.    FUNCTION
  85.     If you want to prevent Executive from exiting/restarting, make
  86.     your program an Executive client. As long as there are clients,
  87.     Executive can't quit.
  88.  
  89.     This is useful if you add tasks to Executive's watched tasks
  90.     list with EXAPI_CMD_WATCH command, they'll disappear if the
  91.     server is restarted.
  92.  
  93.     Remember to remove the client with EXAPI_CMD_REM_CLIENT command.
  94.  
  95.    RESULT
  96.     error - non-zero if error
  97.  
  98.    SEE ALSO
  99.     EXAPI_CMD_REM_CLIENT, <ExecutiveAPI.h>
  100. ExecutiveAPI/EXAPI_CMD_REM_CLIENT                ExecutiveAPI/EXAPI_CMD_REM_CLIENT
  101.  
  102.    NAME
  103.     EXAPI_CMD_REM_CLIENT - Remove client
  104.  
  105.    FUNCTION
  106.     Remove client added using EXAPI_CMD_ADD_CLIENT command.
  107.  
  108.    RESULT
  109.     error - non-zero if error
  110.  
  111.    SEE ALSO
  112.     EXAPI_CMD_ADD_CLIENT, <ExecutiveAPI.h>
  113. ExecutiveAPI/EXAPI_CMD_GET_NICE                  ExecutiveAPI/EXAPI_CMD_GET_NICE
  114.  
  115.    NAME
  116.     EXAPI_CMD_GET_NICE - Get task's nice-value
  117.  
  118.    FUNCTION
  119.     Get task's nice-value.
  120.  
  121.    INPUTS
  122.     task - task address
  123.  
  124.    RESULT
  125.     error - non-zero if error
  126.     value1 - task's nice-value
  127.  
  128.    SEE ALSO
  129.     EXAPI_CMD_SET_NICE, <ExecutiveAPI.h>
  130. ExecutiveAPI/EXAPI_CMD_SET_NICE                  ExecutiveAPI/EXAPI_CMD_SET_NICE
  131.  
  132.    NAME
  133.     EXAPI_CMD_SET_NICE - Set task's nice-value
  134.  
  135.    FUNCTION
  136.     Set task's nice-value. Old nice-value is returned in "value1".
  137.     Allowed values are -20 to +20. Do not specify an illegal
  138.     value because Executive doesn't check the given nice-value.
  139.  
  140.     You should always restore the old nice-value when your
  141.     program exits, if it can be run in a shell. Otherwise
  142.     the shell gets a wrong nice-value.
  143.  
  144.    INPUTS
  145.     task - task address
  146.     value1 - new nice-value (-20 -- +20)
  147.  
  148.    RESULT
  149.     error - non-zero if error
  150.     value1 - task's old nice-value
  151.  
  152.    SEE ALSO
  153.     EXAPI_CMD_GET_NICE, <ExecutiveAPI.h>
  154. ExecutiveAPI/EXAPI_CMD_GET_PRIORITY              ExecutiveAPI/EXAPI_CMD_GET_PRIORITY
  155.  
  156.    NAME
  157.     EXAPI_CMD_GET_PRIORITY - Get task's real priority
  158.  
  159.    FUNCTION
  160.     Ask Executive to return the real (not the scheduling) priority
  161.     of the specified task. If the task is currently scheduled and
  162.     you read the priority directly from task-structure, it will be
  163.     somewhere in the dynamic range. There's no GetTaskPri() routine
  164.     in exec.library which could be patched to return the real
  165.     priority.
  166.  
  167.     In a case a new task is launched with its parent task's priority,
  168.     which is in the dynamic range, Executive notices this, and sets
  169.     the new task's real priority to its parent task's real priority.
  170.     But if wish to create a childtask whose priority will be the
  171.     priority of the parent task plus one, and you read the priority
  172.     from task-structure, it might be something like -58. Add one to
  173.     this value, and you'll get -57. Executive can't correct this, so
  174.     in this case use the EXAPI_CMD_GET_PRIORITY command to obtain
  175.     task's real priority.
  176.  
  177.    INPUTS
  178.     task - task address
  179.  
  180.    RESULT
  181.     error - non-zero if error
  182.     value1 - task's real priority
  183.  
  184.    SEE ALSO
  185.     <ExecutiveAPI.h>
  186. ExecutiveAPI/EXAPI_CMD_WATCH                     ExecutiveAPI/EXAPI_CMD_WATCH
  187.  
  188.    NAME
  189.     EXAPI_CMD_WATCH - Add entries to Executive's watched tasks list
  190.  
  191.    FUNCTION
  192.     This command lets you add entries to Executive's watched task
  193.     list, which contains entries from Executive.prefs, for example:
  194.  
  195.        TASK        NComm    NOSCHEDULE  ABOVE
  196.        CHILDTASKS  XiPaint  RELATIVE
  197.  
  198.     With this command you could add these entries directly from
  199.     the application. See ExecutivePrefs documentation for information
  200.     on what these entries do. Especially the RELATIVE option has some
  201.     restrictions, be sure you know them.
  202.  
  203.     The value1, value2, value3 and value4 items in ExecutiveMessage
  204.     are used as follows:
  205.  
  206.     value1 = EXAPI_TYPE_TASK
  207.              EXAPI_TYPE_CHILDTASKS
  208.  
  209.     value2 = EXAPI_WHICH_SCHEDULE
  210.              EXAPI_WHICH_NOSCHEDULE -> value3 = EXAPI_PRI_LEAVE_ALONE
  211.              EXAPI_WHICH_RELATIVE               EXAPI_PRI_BELOW
  212.                                                 EXAPI_PRI_ABOVE
  213.                                                 EXAPI_PRI_SET -> value4
  214.                                                               (priority)
  215.  
  216.     For example, the "CHILDTASKS XiPaint RELATIVE" entry would be:
  217.  
  218.     msg->value1 = EXAPI_TYPE_CHILDTASKS
  219.     msg->value2 = EXAPI_WHICH_RELATIVE
  220.  
  221.     You can either specify task address or task name. Use task
  222.     address if possible. Executive will duplicate the task name.
  223.     Wildcards (`*') are allowed in the name.
  224.     
  225.     If XiPaint would send the message, it would initialize task
  226.     address:
  227.  
  228.        msg->task = FindTask(NULL)
  229.  
  230.     Executive doesn't check the values, so make sure you specify
  231.     all the necessary values. "value3" is used only with
  232.     EXAPI_WHICH_NOSCHEDULE. "value4" contains task priority if
  233.     EXAPI_PRI_SET is used. EXAPI_WHICH_RELATIVE naturally works
  234.     with EXAPI_TYPE_CHILDTASKS only.
  235.  
  236.     You can issue an EXAPI_CMD_WATCH for a task when the task is
  237.     already running, but for childtasks you have to issue the
  238.     command before any childtasks have been started.
  239.  
  240.     Once you have added an entry into the watched tasks list, you
  241.     can't remove it. It will stay there until Executive exits.
  242.     If you get EXAPI_ERROR_ALREADY_WATCHED error, it means that
  243.     there's already an entry for the specified task. It was either
  244.     added by your task if it was run before, or the entry is in
  245.     Executive.prefs file. In most cases you can safely ignore this
  246.     error.
  247.  
  248.     There's no EXAPI_TYPE_TASK_CHILDTASKS, so use the same message
  249.     twice, just change EXAPI_TYPE_TASK to EXAPI_TYPE_CHILDTASKS and
  250.     resend the message.
  251.  
  252.    INPUTS
  253.     task - task address, or NULL if you want to use task name
  254.     taskname - task name if task address isn't specified
  255.     value1 - task or childtasks
  256.     value2 - schedule, noschedule or relative
  257.     value3 - what to do with task's priority, used with
  258.              EXAPI_TYPE_NOSCHEDULE
  259.     value4 - set task's priority to this value, if EXAPI_PRI_SET
  260.              in value3
  261.  
  262.    RESULT
  263.     error - non-zero if error
  264.  
  265.    SEE ALSO
  266.     <ExecutiveAPI.h>
  267.